Standards for writing software are often regarded with distaste. However, in almost every organization, standards are a fact of life. Standards will be required and enforced for all programs written for any programming course taken at Webster University. These may not be the same exact standards required by any particular company, but these standards will prepare you for programming with any set of standards. In order to receive the maximum grade possible on programming assignments, the student must adhere to these standards.
In general, all data variable names should begin with a lower case letter. The remaining letters in each word should be lower case. Variable names should be meaningful and descriptive of the data that they represent.
Nonstandard: e stuff SUMOFGRADES Department Standard: employee sum_of_grades sumOfGrades
Department Standard: current_customer previous_customer Nonstandard: customer1 customer2
General Rule – Object Variable Names
In general, all object variable names should begin with an upper case letter. The remaining letters in each word should be lower case. Variable names should be meaningful and descriptive of the data that they represent.
Department Standard: Employee Customer Grades Nonstandard: E customer Stuff
Function Names
Function names should generally be a verb phrase (e.g. verb followed by noun). It is acceptable to abbreviate certain common words provided that the abbreviation is well known.
Department Standard: GetMemory ( ) Init_Employee_Struct ( ) CheckMsgTable ( ) Check_Message_Table ( ) Nonstandard: Memory ( ) Initemployeestruct ( ) CkMsgT ( ) Function1 ( )
Data Member Names (Classes and Structures)
When naming member data variables, follow the data variable names rules. Member names (except for the constructor and destructor) should never be the same as the struct or class that defines them.
Department Standard: Airplane.name Employee.firstName Nonstandard: Airplane.airplane Employee.fn
Public Member Function Names (Classes and Structures)
When naming public member functions, follow the rules for function names.
Department Standard: Airplane. SetFuelLevel (
) Employee.Get_Ssn ( ) Nonstandard: Airplane.Fuel ( ) Employee.Gssn ( )
Private Member Function Names (Classes and Structures)
Private member functions should begin with an underscore, and otherwise follow the rules for function names.
Department Standard: Airplane._SetFuelLevel (
) Employee._Calculate_Pay
( ) Nonstandard: Airplane.SetFuelLevel (
) Employee.Calculate_Pay (
)
Pointer names should begin with a lower case ‘p’ followed by the variable name of the data at which they point.
Department Standard: pStudentNumber Employee.pNumber Nonstandard: StudentNumberPtr Employee.PNumber pEmployee.Number
Use const to define constant values. Constants should be uppercase.
Department Standard: const int MAX_CREDITS =
18; const float CM_PER_IN =
2.54; Nonstandard: #define MAX_CREDITS 18 #define CM_PER_IN 2.54
The size of an indent level is 4 columns. If the tab level is set to 4 spaces, then either the space bar or the tab key may be used. The tab character can cause portability problems unless the text editor changes the tab to 4 spaces.
The opening and closing braces of a control structure (e.g. a for statement or an if-else statement) should always be on an otherwise blank line. The curly braces should appear in the same column as the start column of their corresponding control structure. Related (open and close pair) curly braces should always be aligned in the same column.
Department Standard: if ( count == 10 ) { DisplayTotal ( ); } Nonstandard: if ( count == 10 ) { DisplayTotal ( ); }
Department Standard: do { Get_Next_Grade ( ); } while ( grade ! = -99
); Nonstandard: do { Get_Next_Grade ( ); }while ( grade ! = -99
);
Department Standard: for ( x = 0; x < 10 ;
x++ ) { Get_Student_Id ( ); Get_Student_Name (
); } Nonstandard: for ( x = 0; x < 10 ;
x++ ){ Get_Student_Id ( ); Get_Student_Name (
);}
The if statement is coded on a line by itself. Likewise, the else statement is ordinarily coded on a line by itself. However, if the else is followed by an if which is the only if statement subordinate to that else, the if and its conditional expression may go on the same line as the else and no additional nesting or indentation is required.
Department Standard: if ( count == 10 ) { cout << “\n”; } else if ( count > 10
) { cout << “\t”; count = 1; } Nonstandard: if ( count == 10 ) { cout << “\n”; } else { if (count >
10 ) { cout
<< “\t”; count = 1; } }
If a conditional expression is made up of multiple subexpressions, each subexpression should be surrounded in its own set of parentheses.
Department Standard: if ( (count == 10 )
&& (total < 99) ) { cout << “\n”; } Nonstandard: if ( count == 10
&& total < 99 ) { cout << “\n”; }
.
If a conditional expression is made up of multiple subexpressions, and each subexpression is lengthy, then each subexpression should be coded on a separate line.
Department Standard: if (
(count_Before_Adjustment == 10 ) &&
(total_Before_Adjustment < 99) ) &&
(total_After_Adjustment < 99) ) { cout << “\n”; }
.
.
|
Maximum line length of a source code line shall be 78 characters, including all blank characters. Cleanly split longer lines to improve readability. The continued line should be indented.
Department Standard: cout << setw
( 25 ) << Employee.first_Name <<
setw ( 10 ) << Employee.last _Name <<
setw ( 35 ) << Employee.home_Address;
Nonstandard: cout << setw
( 25 ) << Employee.First_Name << setw ( 10 ) <<
Employee.last _Name << setw ( 35 ) <<
Employee.home_Address
Inline comments associated declarations should be aligned with one another, in a column which is also associated with a tab stop.
Department Standard: int student_id, //
student SSN or number or id credits; //
number of credits of enrollment
Nonstandard: int student_id, //
student SSN or number or id credits; //
number of credits of enrollment
When the control structure (e.g., while, if, for) has only one statement in its body, it should still be coded so that the single statement is enclosed in curly braces (even though the braces are not required in C++).
Department Standard: if ( count == 10 ) { DisplayTotal ( ); } Nonstandard: if ( count == 10 ) DisplayTotal ( ); Nonstandard: if ( count == 10 )
DisplayTotal ( );
The use of goto and break to terminate loop structure is not permitted. The use of ‘break’ is restricted to ‘switch’ statements. Goto is never permitted. Every block of code should have one entry and one exit point;
Every function should have exactly one entry point and one exit point. It is never permissible to use more than one return statement in a function.
Department Standard: int total = 0; if ( count == 10 ) { total = 7; } else { total = 3; } return total; Nonstandard: if ( count == 10 ) { return ( 7 ); } else { return ( 3 ); }
One Statement Per Line
Each coding line should contain only one statement.
Department Standard: total = 0; average = 0.0; Nonstandard: total = 0; average =
0.0;
Pointer and Reference Parameter Declaration
Pointers should be declared with the . * part of the type.
Reference variables should also associate the & with the type;
Department Standard: int* pStudent; int* pNumber; Nonstandard: int *pStudent, *pNumber; Department Standard: void swap (int&
num1, int&
num2) Nonstandard: void swap (int
&num1, int
&num2)
Variable Declaration Style
Each variable must be declared on a separate line. Group variables of the same data type together and indent to the same level.
Department Standard: int number_students, test_number; float student_average, class_average; Nonstandard: int number_students,
test_number; float student_average,
class_average;
|
Use C++ not C Statements
C++ is not C. Do not write C code, compile it with a C++ compiler, and try to pretend that it's C++.
Department Standard: cout << Total; Nonstandard: printf (“%d”,Total );
Department Standard: // comments Nonstandard: /* comments */
Use Reference Parameters
Avoid using pointers when reference parameters can accomplish the same goal. Pointers to pointers should always be avoided. Unlike a pointer, a reference cannot be changed to point to another object or variable.
Department Standard: void swap (int&
num1,
int& num2) Nonstandard: void swap (int * num1, int*
num2)
Use if-else not ?:
Avoid using the ? : operators. Even though it is fewer keystrokes, it diminishes readability of the program. The days of terse cryptic code are over. Make it readable. Always make the code obvious.
Nonstandard: total = count == 10
?7:3; Department Standard: if ( count == 10 ) { total = 7; } else { total = 3; }
Eliminate All Compiler Warnings
Eliminate all compiler warnings. The most common warnings that students encounter are “unreferenced local variable” or “truncation – possible loss of data”. These warnings are there for a reason – correct the program syntax so that the code compiles with no warnings.
Department Standard: --------------------Configuration:
minmax - Win32 Debug-------------------- Compiling... minmax.cpp Linking... minmax.exe - 0 error(s),
0 warning(s)
Nonstandard: --------------------Configuration:
minmax - Win32 Debug-------------------- Compiling... minmax.cpp minmax.cpp(22) : warning
C4244: '=' : conversion from 'double' to 'int', possible loss of data minmax.cpp(19) : warning
C4101: 'i' : unreferenced local variable minmax.cpp(25) : warning
C4700: local variable 'min' used without having been initialized Linking... minmax.exe - 0 error(s),
3 warning(s)
NO “magic numbers”
Integer literals should be replaced by constant identifiers
Department Standard: const int TAX_RATE =
.073; price = cost * (1 +
TAX_RATE); Nonstandard: price = cost * 1.073;
Use “White Space”
Insert blank lines between declarations and statements and between blocks of related statements to make clear the structure of the program.
Use a space before and after every operator or assignment symbol.
Department Standard: x = y + 2 / z; Nonstandard: x=y+2/z;
Department Standard: cin >>
minimum; cout << setw(7)
<< minimum; Nonstandard: cin>>minimum; cout<<setw(7)<<minimum;
Principle 1: Programs and Functions should be well structured
a. Use a modular approach for a complex problems.
b. Use local variables within functions when the variable is used only within that function.
c. Use parameters to pass information to and from functions. NO global variables.
d. To protect arguments that should not be modified by a function, declare the parameters to be value parameters or constant reference parameters rather than reference parameters.
e. Use accessor methods (get/set member functions) instead of public variables in objects. All data members should be private.
f. Variables should not be reused for different purposes within the same function.
Principle 2: All Source Code Should be Documented
a. Each program MUST include opening documentation.
b. Comments should be used only to explain key code segments when the meaning is not obvious.
c. Do not use documentation that restates the obvious. It tends to serve no purpose other than to clutter the program for the reader.\
d. Strive for simplicity and clarity. Clever programming tricks should be avoided when clarity is compromised.
e. Every effort should be made to make code clear through good design, simplicity, good naming and layout. Comments are required where code is not clear.
Principle 3: Source Code should be Formatted in a Style that Enhances Readability
a) Insert blank lines between declarations and statements and between blocks of statements to make clear the structure of the program.
b) Declare constants and variables at the top of a function.
c) Label all output produced by a program.
d) Separate functions by a row of commented stars( //******)
A heading should appear at the beginning of each file of a program that conforms to the following format:
//******************************************************************************
//
// File: max.cpp
//
// Student: Sam Student
//
// Assignment: Program #1
//
// Course Name: Programming 1
//
// Course Number: COSC 1540 - 01
//
// due: Dec 19, 2002
//
//
// This program asks the user to read a file
// of integers from a disk file and then
// determines the maximum of the
// three numbers.
//
// Other files required:
// 1. numbers.txt – text file of integers
// 2. max.h – prototypes for all functions
// needed by max.cpp
//
//
//******************************************************************************
All functions should be separated by a row of commented stars:
//******************************************************************************
|